Certificate Operations

Before adding a certificate to a certificate store in Keyfactor Command, you must approve an orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. to handle the store and create a record for the store in Keyfactor Command. See Orchestrator Management and Certificate Store Operations.

To add a certificate to a certificate store:

1. Highlight the row in the results grid and right-click.
2. Choose Add to a Certificate Store from the right-click menu.

3. When you select the Add to Certificate Store option the Select Certificate Store Locations dialog opens. When you select the certificate stores to which you want to deploy your certificate and click Include, the Add to Certificate Stores dialog appears BEHIND the Select Certificate Store Locations dialog, holding your selection and leaving the Select Certificate Store Locations dialog open for you to continue selecting locations. The final list of selections will only be accessible once you close the Select Certificate Store Locations dialog using the Include and Close button.

   Select Certificate Store Locations

   The Select Certificate Store Locations dialog allows you to run queries against your certificate store list to select which store(s) to deploy a selected certificate to. Check the box next to each certificate store location to which you want to distribute the certificate.

   Note:   Only compatible certificate stores and only stores in containers to which you have permissions are shown on the grid.

   Tip:  You may change the search results by using the search fields at the top of the dialog. All of the Keyfactor Command grid search features are available to assist your search. See Using the Certificate Store Search Feature for more information on the available search fields. The default search criteria is AgentAvailable is equal to True.

   The actions on the Select Certificate Store Locations dialog are:

   • Include
     Click this to add the selected certificate store(s) to your certificate selection and leave the search dialog open for further searches.
   • Include and Close
     Click this to close the search dialog and add the selected certificate store(s) to your certificate selection, which will then be displayed and ready for updates as per the instructions in Add to Certificate Stores.
   • Close
     Click this to cancel the operation and return to the main page with no certificate stores selected.

   

   Figure 30: Select Certificate Store Locations Dialog

   Add to Certificate Stores

   The Add to Certificate Stores page appears once you select at least one certificate store to distribute your certificate to. It includes a grid section with a series of tabs that display a tab for each type of certificate store selected with a list of the selected stores under each tab. The header section of the dialog shows global options that apply to the add job as a whole:

   • Include Certificate Stores

     You may return to the Select Certificate Store Locations dialog by clicking Include Certificate Stores above the grid. The current selections will be retained.

   • Schedule when to run the job for the certificate store

     In the Schedule dropdown, select a time at which the job to add the certificate to the stores should run. The choices are Immediate or Exactly Once at a specified date and time. If you choose Exactly Once, enter the date and time for the job. A job scheduled for Immediate running will run within a few minutes of saving the operation. The default is Immediate.

   • Include Private Key on Certificate Stores when the Private Key is optional

     Check the Include Private Key box if you want to deliver the private key of the certificate to any selected certificate stores that do not require a private key (e.g. Java keystores). This option only appears for certificates that have a private key available for distribution.

   Click Remove at the top of the grid to remove the selected certificate store from the page. The certificate will not be added to the store.

   For each selected certificate store you can apply the following actions:

   • Overwrite

     Check Overwrite below the grid to overwrite any existing certificate in the same location and with the same name or alias for the selected certificate store type.

   • Alias

     Add an Alias below the grid, if applicable, for the certificate store type. See the Information Required by Certificate Store section, below, for more information.

     Note:   The tab heading of the certificate location will display an alert if an alias is required for the location. If this is set to Forbidden on the certificate store type, the Alias field will not display unless "Overwrite" is checked on this page.

   

   Figure 31: Add Certificate—Install into Certificate Locations

   

   Figure 32: Alias Required Alert on Save

   Information Required by Certificate Stores

   Each type of certificate store has different requirements for providing an alias or other additional information. Table 5: Alias Requirements by Certificate Store Type provides a quick breakdown by certificate store of whether a certificate alias is required for new certificate additions or only for overwriting an existing certificate in the store.

   Tip:  When adding a certificate to a certificate store, you have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite. Find the alias values by navigating to Management Portal > Certificates > Certificate Search. Select the certificate you wish to overwrite and double-click, or click Edit, from the grid header or right-click menu. Choose the Locations tab and double-click on the Location Type (this must have a number other than zero in the Count column) to open the details dialog. The Alias field holds the information that may be required for an overwrite.

   

   Figure 33: Example: Certificate Location Details for a JKS Location

   Table 5: Alias Requirements by Certificate Store Type

   Certificate Store Type	Alias Functionality
   Amazon Web Services	Alias only required for overwrites
   F5 CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. Bundles REST	Alias required for new additions and overwrites
   F5 SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. Profiles	Alias required for new additions and overwrites
   F5 SSL Profiles REST	Alias required for new additions and overwrites
   F5 Web Server	Alias only required for overwrites
   F5 Web Server REST	Alias only required for overwrites
   File Transfer Protocol	Alias required for new additions and overwrites
   IIS Personal	Alias only required for overwrites
   IIS Revoked	Alias not needed
   IIS Trusted Roots	Alias not needed
   Java Keystore A Java KeyStore (JKS) is a file containing security certificates with matching private keys. They are often used by Java-based applications for authentication and encryption.	Alias required for new additions and overwrites
   NetScaler	Alias required for new additions and overwrites
   PEM A PEM format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PEM certificates always begin and end with entries like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. PEM certificates can contain a single certificate or a full certifiate chain and may contain a private key. Usually, extensions of .cer and .crt are certificate files with no private key, .key is a separate private key file, and .pem is both a certificate and private key. File	Alias only required for overwrites

   Amazon Web Services (AWS)

   Amazon Web Services (AWS) certificate stores require the addition of a private key and will only appear as an option when you select a certificate with a private key. With this type of store, you have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite. The alias is the internal ID assigned by Amazon (the Amazon resource number or ARN). Provide the entire contents of the Alias/IP from this field when entering an alias for overwrite. For example:

   arn:aws:acm:us-west-2:220531701668:certificate/88e5dcfb-a70b-4636-a8ab-e85e8ad88780

   F5 CA Bundles REST

   F5 CA Bundle REST certificate store additions do not require the addition of a private key and will appear for both certificates with a private key and those without. With this type of store, you will be prompted to add an alias for the certificate. The alias is the file name used to store the file in the device file system, minus the extension (e.g. use alias MyFile for a file named MyFile.crt). Aliases should be entered without spaces. Note that certificate names are case sensitive. You have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite.

   F5 SSL Profile

   F5 SSL Profile certificate store additions do not require the addition of a private key and will appear for both certificates with a private key and those without. With this type of store, you will be prompted to add an alias for the certificate. The alias is the file name used to store the file in the device file system, minus the extension (e.g. use alias MyFile for a file named MyFile.pfx). Aliases should be entered without spaces. Note that certificate names are case sensitive. You have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite.

   F5 SSL Profile REST

   F5 SSL Profile REST certificate store additions do not require the addition of a private key and will appear for both certificates with a private key and those without. With this type of store, you will be prompted to add an alias for the certificate. The alias is the file name used to store the file in the device file system, minus the extension (e.g. use alias MyFile for a file named MyFile.pfx). Aliases should be entered without spaces. Note that certificate names are case sensitive. You have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite.

   F5 Web Server

   F5 Web Server certificate stores require the addition of a private key and will only appear as an option when you select a certificate with a private key. With this type of store, you have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite. The alias for F5 device certificates is typically "server".

   F5 Web Server REST

   F5 Web Server REST certificate stores require the addition of a private key and will only appear as an option when you select a certificate with a private key. With this type of store, you have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite. The alias for F5 device certificates is typically "server".

   File Transfer Protocol (FTP)

   File Transfer Protocol (FTP) certificate store additions do not require the addition of a private key and will appear for both certificates with a private key and those without. With this type of store, you have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite. In that case the new thumbprint should be passed in as the alias without any spaces between the octets (e.g. 81009c6e5465ecf343ba55ff9612122a5a4f6b33 not 81 00 9c 6e 54 65 ec f3 43 ba 55 ff 96 12 12 2a 5a 4f 6b 33).

   IIS Personal

   IIS Personal certificate stores require the addition of a private key and will only appear as an option when you select a certificate with a private key. With this type of store, you have the option to overwrite an existing certificate bound to an IIS web site with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite. The alias is the thumbprint of the certificate bound to the IIS web site on the target. The thumbprint may be entered with or without spaces between each octet (e.g. 81 00 9c 6e 54 65 ec f3 43 ba 55 ff 96 12 12 2a 5a 4f 6b 33 or 81009c6e5465ecf343ba55ff9612122a5a4f6b33).

   Tip:  Choosing overwrite for a certificate not bound to an IIS web site will have no effect. No certificate will be overwritten.

   IIS Revoked and Trusted Root

   IIS Revoked and Trusted Root certificate store additions do not require the addition of a private key and will appear for both certificates with a private key and those without.

   Tip:  The overwrite functionality is not relevant for IIS Revoked and Trusted Root certificate stores and should be ignored.

   Java Keystore

   Java keystore certificate store additions do not require the addition of a private key and will appear for both certificates with a private key and those without. With this type of store, you will be prompted to add an alias for the certificate. This optional alias is stored in the keystore associated with the certificate. You have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite. Spaces are supported in the alias.

   NetScaler

   NetScaler certificate store additions do not require the addition of a private key and will appear for both certificates with a private key and those without. With this type of store, you will must add an Alias for the certificate. This serves as the file name used to store the file in the file system, so provide it with an appropriate extension (e.g. appserver17.crt or appserver17.pfx). Aliases should be entered without spaces. You must also enter the virtual server to associate the certificate with in the NetscalerVserver field. For a certificate with a private key, you are associating the certificate as a NetScaler Server Certificate. For a certificate without a private key, you are associating the certificate as a NetScaler CA Certificate and only CA certificates are supported for this purpose. You will receive an error if you attempt to associate a non-CA certificate without a private key with a virtual server. Entry of virtual server name is not case sensitive. You have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias (full file name with extension) of the certificate you wish to overwrite.

   PEM File

   PEM certificate store additions do not require the addition of a private key and will appear for both certificates with a private key and those without. With this type of store, you have the option to overwrite an existing certificate with the current certificate. If you choose this option, you will need to provide the alias of the certificate you wish to overwrite. The alias is the thumbprint of the certificate without any spaces between the octets (e.g. 81009c6e5465ecf343ba55ff9612122a5a4f6b33 not 81 00 9c 6e 54 65 ec f3 43 ba 55 ff 96 12 12 2a 5a 4f 6b 33).

   Note:   Keyfactor Command will automatically strip out any spaces between the octets in the alias field, so it does not matter whether you enter the thumbprint with or without spaces.
4. Click Save to submit the certificate store additions.

Select one or more certificates in the results grid and then click Delete at the top of the grid or Delete in the right-click menu to remove the selected certificate(s) from the Keyfactor Command database. If the selected certificates have associated private keys stored in the database, these private keys are also removed. The certificates will be returned to the Keyfactor Command database on the next full synchronization if synchronization for the certificate source (certificate authority A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA., SSL endpoint An endpoint is a URL that enables the API to gain access to resources on a server., etc.) is still configured. Certificate history and private keys do not return when certificates re-synchronize.

This option is available only in saved collections, not in standard certificate searches. Click the Delete All action button at the top of the collection grid. The button appears active only if no certificates are selected on the grid. A large deletion may take several minutes to complete. The certificates will be returned to the Keyfactor Command database on the next full synchronization if synchronization for the certificate source (certificate authority, SSL endpoint, etc.) is still configured.

Click the Delete Private Key in the right-click menu to remove the private key of the selected certificate(s) from the Keyfactor Command database. This option is only available if the private key is stored in the database.

Click Downland in the right-click menu to download the selected certificate to the local computer with or without a private key. Only one certificate may be downloaded at a time.

You will be able to download a certificate including its private key if one of the following is true:

• The certificate has been stored in the Keyfactor Command database with its private key.

• The certificate was issued using a template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. that had key archival enabled, issued from a Microsoft CA that has a valid Key Recovery Agent certificate, and that Key Recovery Agent certificate is configured on the Keyfactor Command server.

  Important:  In order to successfully download certificates and retrieve their associated private keys using Microsoft key recovery, the service account under which the Keyfactor Command application pool is running must be granted "Issue and Manage Certificates" permission to the CA database as per Create Active Directory Groups to Control Access to Keyfactor Command Features in the Keyfactor Command Server Installation Guide, or, if delegation is configured for the CA, the user executing the download must have these permissions.
  
  In order to support key recovery within Keyfactor Command, you need to import at least one Key Recovery Agent certificate with a private key into the Keyfactor Command application pool user’s personal certificate store on each Management Portal server. See Configuring Key Recovery for Keyfactor Command.
  Tip:  CA-level key recovery is supported for Microsoft CAs to allow recovery of private keys for certificates enrolled outside of Keyfactor Command. CA-level key archiving is not supported for enrollments done through Keyfactor Command. CA-level key recovery is not supported for EJBCA CAs. For enrollments done through Keyfactor Command for either Microsoft or EJBCA CAs, use Keyfactor Command private key retention (see Details Tab).

To download a certificate that has the private key stored in the Keyfactor Command database:

1. Highlight the row in the results grid and right-click.
2. Choose Download from the right-click menu, or the action button on the Certificate Details dialog.

   

   Figure 34: Certificate Operation: Download Certificate with Private Key

3. In the Download dialog, select the Include Private Key option to include the private key of the certificate in the download. If you choose Include Private Key for a PFX or PEM certificate with a private key, after you click Download (step 6 below), PFX/PEM Password dialog will pop-up with the one-time password and action buttons to Copy Password or Close the pop-up. Clicking Copy Password will copy the password to the clipboard. As a security measure, the dialogue will close after 2 minutes. To secure the downloaded file, you will need this password in order to access the PFX or PEM file generated by the download. Click Close to close the PFX/PEM Password dialog once you have copied the password.

   

   Important:  The randomly generated password cannot be regenerated, so it must be copied prior to closing the dialog.
4. Select Include Chain to include the certificate chain (root and intermediate certificates) in the download.
5. Chose an encoding format. Selecting the Include Private Key and Include Chain options changes which formats are available.
6. Click Download to begin the download.

To download a certificate that does not have the private key stored in the Keyfactor Command database:

1. Highlight the row in the results grid and right-click.
2. Choose Download from the right-click menu.

   

   Figure 35: Certificate Operation: Download Certificate without Private Key

3. Select Include Chain to include the certificate chain (root and intermediate certificates) in the download.
4. If Include Chain is selected, chose an encoding format of PEM or P7B A PKCS #7 format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PKCS #7 certificates always begin and end with entries that look something like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. Unlike PEM files, PKCS #7 files can contain only a certificate and its certifiate chain but NOT its private key. Extensions of .p7b or .p7c are usually seen on certificate files of this format.. If Include Chain is not selected, chose an encoding format of PEM or DER A DER format certificate file is a DER-encoded binary certificate. It contains a single certificate and does not support storage of private keys. It sometimes has an extension of .der but is often seen with .cer or .crt..
5. Click Download to begin the download.

Select one certificate in the results grid and then click Edit at the top of the grid, or Edit in the right-click menu, or double-click the row, to pop up the certificate details dialog box in which you can view details of the certificate data and edit metadata fields for the certificate. Users without Edit Metadata permissions to certificates will see a Display option instead of an Edit option.

Note, the certificate details dialog also includes buttons for the download, revoke, and renew (if applicable) operations for users with appropriate permissions. You cannot change any of the certificate attributes from Certificate Authority (shown on the Content tab) or any of the certificate status, validation, locations, or history data tracked by Keyfactor Command (shown on the Status, Validation, Locations and History tabs).

See Certificate Details for more detailed information about the certificate details dialog.

If you select multiple certificates to edit at once, only the metadata fields dialog will appear. See Edit All.

Click Edit All at the top of the grid to open the metadata fields for all of the certificates in the query for editing. The button appears active only if no certificates are selected on the grid. All defined metadata fields—including those marked hidden—appear on the Edit All dialog. Each field includes an alert button that identifies whether the certificates in the query have all of same () or different () values for each metadata field. Click the alert button for an explanation of the impact the Overwrite settings for this field will have on the certificates.

See Metadata Tab for more detailed information about the certificate details metadata.

Click Allow Modifying to enable the field for editing. Editing a field and selecting Overwrite will change the value for all certificates. Editing this field and not selecting Overwrite will only change the value for certificates that do not already have a value defined for this field.

Click Get CSV from the top of the grid to download all the certificates in the results grid to a comma-delimited CSV file. The button appears active only if no certificates are selected on the grid.

The CSV file will contain the following information for each exported certificate:

• Issued DN A distinguished name (DN) is the name that uniquely identifies an object in a directory. In the context of Keyfactor Command, this directory is generally Active Directory. A DN is made up of attribute=value pairs, separated by commas. Any of the attributes defined in the directory schema can be used to make up a DN.
• Import Date
• Effective Date
• Expiration Date
• Issued CN A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com).
• Certificate Authority Name
• Template Display Name
• Principal
• Requester
• Key Type The key type identifies the type of key to create when creating a symmetric or asymmetric key. It references the signing algorithm and often key size (e.g. AES-256, RSA-2048, Ed25519).
• Key Size The key size or key length is the number of bits in a key used by a cryptographic algorithm.
• Certificate State
• Thumbprint

A confirmation dialog will pop up providing an approximate file size of the file that will be generated. A CSV file generated from a very large result set may take a long time to download or may be unwieldy to edit.

Click Identity Auditin the right-click menu to view the certificate level permissions (read, edit metadata, download with private key, revoke, and delete) granted to all user roles defined in Keyfactor Command (see Security Roles and Identities) for the selected certificate.

Click Remove from Certificate Store in the right-click menu to remove the selected certificate from a certificate store or stores. Two dialog boxes will pop up as per Add to Certificate Store allowing you to select the certificate store(s) from which you wish to remove the certificate. In the first dialog, select the certificate store from which you want to remove the certificate and click the Include and Close button and then click Save in the second dialog. Only certificate stores that contain the certificate and to which the user has permissions will be shown.

Click Renew in the right-click menu to renew or re-issue the selected certificate.

The renewal dialog includes the options of one-click renewal (the Continue option), which supports renewal with no further user interaction, or seeded PFX enrollment (the Configure option), to be redirected to the PFX Enrollment page with the information for the certificate pre-populated in the enrollment fields. The Continue option is only available if either one of the following is true:

• The certificate is located together with its private key in one or more managed certificate store(s).
• The certificate was enrolled with a template that has been configured in Keyfactor Command to allow private keys to be encrypted and stored in the Keyfactor Command database (see Certificate Template Operations).

From the seeded PFX Enrollment page, you can change the CA or template for enrollment, change the subject information or metadata for the certificate, set or remove SANs, or change the certificate store(s) to which the renewed certificate will be distributed. To change the certificate store(s) for distribution, on the PFX Enrollment page, scroll down to the Certificate Delivery Format section and click the Include Certificate Stores button. This will open the Select Certificate Store Locations dialog. For more information, see Add to Certificate Store and PFX Enrollment.

Certificates issued by Microsoft CAs will be renewed (meaning the certificate will be issued with a different private key) regardless of how recently they were issued. Certificates issued by other certificate authorities will be renewed (typically retaining the same private key but with a new expiration date) if they are within the renewal window specified by the certificate template and re-issued (retaining the same expiration date) if they are not yet within the renewal window.

Select one or more certificates in the results grid and then click Revoke to revoke the selected certificate(s). When you select revoke, a dialog box pops up prompting for the effective revocation date, the reason for the revocation (for which there are dropdown choices), and comments (required). Upon completion of the revocation, the CRL A Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date and should no longer be trusted. for the CA in question is immediately republished to reflect the revocation. Unless you choose the revocation reason of Certificate Hold, there is no way to undo a revoke so care should be taken with this operation.

If you would like to suspend one or more certificates without permanently revoking them, select one or more certificates in the results grid and then click Revoke at the top of the grid or Revoke on the right-click menu. Select Certificate Hold as the revocation reason. You will be required to add a comment in the Comments field to Save the record change.

When you Revoke a certificate using the revocation reason of Certificate Hold, the certificate is in the revoked state, with the revocation reason of Certificate Hold. You will only be able to see the certificate on a certificate search with Include Revoked checked. To return the certificate to the Active state, Revoke it again with the reason Remove from Hold. You will be required to add a comment in the Comments field to Save the record change.

If you would like to revoke ALL the certificates in the current query results set, click Revoke All at the top of the grid. The button appears active only if no certificates are selected on the grid.

When you select revoke all, a dialog box pops up prompting for the effective revocation date, the reason for the revocation (for which there are dropdown choices), comments (required), and confirmation of the number of certificates being revoked. Upon completion of the revocations, the CRL(s) for the CA(s) in question is immediately republished to reflect the revocations. Unless you choose the revocation reason of Certificate Hold, there is no way to undo a revoke so care should be taken with this operation.

A maximum of 1000 certificates can be revoked at once with this option. If the query contains more certificates than this, a warning dialog will appear and you will not be allowed to continue with the revocation.